home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / AppleEvents.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  13.7 KB  |  361 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        AppleEvents.h
  3.  
  4.      Contains:    AppleEvent Package Interfaces.
  5.  
  6.      Version:    Technology:    System 7.5
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1989-1997 by Apple Computer, Inc., all rights reserved
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __APPLEEVENTS__
  19. #define __APPLEEVENTS__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __MIXEDMODE__
  25. #include <MixedMode.h>
  26. #endif
  27. #ifndef __NOTIFICATION__
  28. #include <Notification.h>
  29. #endif
  30. #ifndef __EVENTS__
  31. #include <Events.h>
  32. #endif
  33. /*
  34.     Note:    The functions and types for the building and parsing AppleEvent  
  35.             messages has moved to AEDataModel.h
  36. */
  37. #ifndef __AEDATAMODEL__
  38. #include <AEDataModel.h>
  39. #endif
  40.  
  41.  
  42.  
  43. #if PRAGMA_ONCE
  44. #pragma once
  45. #endif
  46.  
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50.  
  51. #if PRAGMA_IMPORT
  52. #pragma import on
  53. #endif
  54.  
  55. #if PRAGMA_STRUCT_ALIGN
  56.     #pragma options align=mac68k
  57. #elif PRAGMA_STRUCT_PACKPUSH
  58.     #pragma pack(push, 2)
  59. #elif PRAGMA_STRUCT_PACK
  60.     #pragma pack(2)
  61. #endif
  62.  
  63.  
  64. enum {
  65.                                                                 /* Keywords for Apple event parameters */
  66.     keyDirectObject                = FOUR_CHAR_CODE('----'),
  67.     keyErrorNumber                = FOUR_CHAR_CODE('errn'),
  68.     keyErrorString                = FOUR_CHAR_CODE('errs'),
  69.     keyProcessSerialNumber        = FOUR_CHAR_CODE('psn '),        /* Keywords for special handlers */
  70.     keyPreDispatch                = FOUR_CHAR_CODE('phac'),        /* preHandler accessor call */
  71.     keySelectProc                = FOUR_CHAR_CODE('selh'),        /* more selector call */
  72.                                                                 /* Keyword for recording */
  73.     keyAERecorderCount            = FOUR_CHAR_CODE('recr'),        /* available only in vers 1.0.1 and greater */
  74.                                                                 /* Keyword for version information */
  75.     keyAEVersion                = FOUR_CHAR_CODE('vers')        /* available only in vers 1.0.1 and greater */
  76. };
  77.  
  78. /* Event Class */
  79.  
  80. enum {
  81.     kCoreEventClass                = FOUR_CHAR_CODE('aevt')
  82. };
  83.  
  84. /* Event ID’s */
  85.  
  86. enum {
  87.     kAEOpenApplication            = FOUR_CHAR_CODE('oapp'),
  88.     kAEOpenDocuments            = FOUR_CHAR_CODE('odoc'),
  89.     kAEPrintDocuments            = FOUR_CHAR_CODE('pdoc'),
  90.     kAEQuitApplication            = FOUR_CHAR_CODE('quit'),
  91.     kAEAnswer                    = FOUR_CHAR_CODE('ansr'),
  92.     kAEApplicationDied            = FOUR_CHAR_CODE('obit')
  93. };
  94.  
  95. /* Constants for recording */
  96.  
  97. enum {
  98.     kAEStartRecording            = FOUR_CHAR_CODE('reca'),        /* available only in vers 1.0.1 and greater */
  99.     kAEStopRecording            = FOUR_CHAR_CODE('recc'),        /* available only in vers 1.0.1 and greater */
  100.     kAENotifyStartRecording        = FOUR_CHAR_CODE('rec1'),        /* available only in vers 1.0.1 and greater */
  101.     kAENotifyStopRecording        = FOUR_CHAR_CODE('rec0'),        /* available only in vers 1.0.1 and greater */
  102.     kAENotifyRecording            = FOUR_CHAR_CODE('recr')        /* available only in vers 1.0.1 and greater */
  103. };
  104.  
  105.  
  106. /* parameter to AESend */
  107. typedef OptionBits                         AESendOptions;
  108.  
  109. enum {
  110.     kAENeverInteract            = 0x00000010,                    /* server should not interact with user */
  111.     kAECanInteract                = 0x00000020,                    /* server may try to interact with user */
  112.     kAEAlwaysInteract            = 0x00000030,                    /* server should always interact with user where appropriate */
  113.     kAECanSwitchLayer            = 0x00000040,                    /* interaction may switch layer */
  114.     kAEDontRecord                = 0x00001000,                    /* don't record this event - available only in vers 1.0.1 and greater */
  115.     kAEDontExecute                = 0x00002000,                    /* don't send the event for recording - available only in vers 1.0.1 and greater */
  116.     kAEProcessNonReplyEvents    = 0x00008000                    /* allow processing of non-reply events while awaiting synchronous AppleEvent reply */
  117. };
  118.  
  119. typedef SInt32                             AESendMode;
  120.  
  121. enum {
  122.     kAENoReply                    = 0x00000001,                    /* sender doesn't want a reply to event */
  123.     kAEQueueReply                = 0x00000002,                    /* sender wants a reply but won't wait */
  124.     kAEWaitReply                = 0x00000003,                    /* sender wants a reply and will wait */
  125.     kAEDontReconnect            = 0x00000080,                    /* don't reconnect if there is a sessClosedErr from PPCToolbox */
  126.     kAEWantReceipt                = 0x00000200                    /* (nReturnReceipt) sender wants a receipt of message */
  127. };
  128.  
  129.  
  130. /* Constants for timeout durations */
  131.  
  132. enum {
  133.     kAEDefaultTimeout            = -1,                            /* timeout value determined by AEM */
  134.     kNoTimeOut                    = -2                            /* wait until reply comes back, however long it takes */
  135. };
  136.  
  137.  
  138. /* priority param of AESend */
  139. typedef SInt16                             AESendPriority;
  140.  
  141. enum {
  142.     kAENormalPriority            = 0x00000000,                    /* post message at the end of the event queue */
  143.     kAEHighPriority                = 0x00000001                    /* post message at the front of the event queue (same as nAttnMsg) */
  144. };
  145.  
  146.  
  147. typedef SInt8                             AEEventSource;
  148.  
  149. enum {
  150.     kAEUnknownSource            = 0,
  151.     kAEDirectCall                = 1,
  152.     kAESameProcess                = 2,
  153.     kAELocalProcess                = 3,
  154.     kAERemoteProcess            = 4
  155. };
  156.  
  157.  
  158.  
  159. typedef CALLBACK_API( OSErr , AEEventHandlerProcPtr )(const AppleEvent *theAppleEvent, AppleEvent *reply, UInt32 handlerRefcon);
  160. typedef CALLBACK_API( Boolean , AEIdleProcPtr )(EventRecord *theEvent, long *sleepTime, RgnHandle *mouseRgn);
  161. typedef CALLBACK_API( Boolean , AEFilterProcPtr )(EventRecord *theEvent, long returnID, long transactionID, const AEAddressDesc *sender);
  162. typedef STACK_UPP_TYPE(AEEventHandlerProcPtr)                     AEEventHandlerUPP;
  163. typedef STACK_UPP_TYPE(AEIdleProcPtr)                             AEIdleUPP;
  164. typedef STACK_UPP_TYPE(AEFilterProcPtr)                         AEFilterUPP;
  165. enum { uppAEEventHandlerProcInfo = 0x00000FE0 };                 /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  166. enum { uppAEIdleProcInfo = 0x00000FD0 };                         /* pascal 1_byte Func(4_bytes, 4_bytes, 4_bytes) */
  167. enum { uppAEFilterProcInfo = 0x00003FD0 };                         /* pascal 1_byte Func(4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  168. #define NewAEEventHandlerProc(userRoutine)                         (AEEventHandlerUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppAEEventHandlerProcInfo, GetCurrentArchitecture())
  169. #define NewAEIdleProc(userRoutine)                                 (AEIdleUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppAEIdleProcInfo, GetCurrentArchitecture())
  170. #define NewAEFilterProc(userRoutine)                             (AEFilterUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppAEFilterProcInfo, GetCurrentArchitecture())
  171. #define CallAEEventHandlerProc(userRoutine, theAppleEvent, reply, handlerRefcon)  CALL_THREE_PARAMETER_UPP((userRoutine), uppAEEventHandlerProcInfo, (theAppleEvent), (reply), (handlerRefcon))
  172. #define CallAEIdleProc(userRoutine, theEvent, sleepTime, mouseRgn)  CALL_THREE_PARAMETER_UPP((userRoutine), uppAEIdleProcInfo, (theEvent), (sleepTime), (mouseRgn))
  173. #define CallAEFilterProc(userRoutine, theEvent, returnID, transactionID, sender)  CALL_FOUR_PARAMETER_UPP((userRoutine), uppAEFilterProcInfo, (theEvent), (returnID), (transactionID), (sender))
  174.  
  175. /**************************************************************************
  176.   The next couple of calls are basic routines used to create, send,
  177.   and process AppleEvents. 
  178. **************************************************************************/
  179. EXTERN_API( OSErr )
  180. AESend                            (const AppleEvent *        theAppleEvent,
  181.                                  AppleEvent *            reply,
  182.                                  AESendMode             sendMode,
  183.                                  AESendPriority         sendPriority,
  184.                                  long                     timeOutInTicks,
  185.                                  AEIdleUPP                 idleProc,
  186.                                  AEFilterUPP             filterProc)                            THREEWORDINLINE(0x303C, 0x0D17, 0xA816);
  187.  
  188. EXTERN_API( OSErr )
  189. AEProcessAppleEvent                (const EventRecord *    theEventRecord)                        THREEWORDINLINE(0x303C, 0x021B, 0xA816);
  190.  
  191.  
  192. /* 
  193.  Note: during event processing, an event handler may realize that it is likely
  194.  to exceed the client's timeout limit. Passing the reply to this
  195.  routine causes a wait event to be generated that asks the client
  196.  for more time. 
  197. */
  198. EXTERN_API( OSErr )
  199. AEResetTimer                    (const AppleEvent *        reply)                                THREEWORDINLINE(0x303C, 0x0219, 0xA816);
  200.  
  201.  
  202. /**************************************************************************
  203.   The following three calls are used to allow applications to behave
  204.   courteously when a user interaction such as a dialog box is needed. 
  205. **************************************************************************/
  206.  
  207. typedef SInt8                             AEInteractAllowed;
  208.  
  209. enum {
  210.     kAEInteractWithSelf            = 0,
  211.     kAEInteractWithLocal        = 1,
  212.     kAEInteractWithAll            = 2
  213. };
  214.  
  215. EXTERN_API( OSErr )
  216. AEGetInteractionAllowed            (AEInteractAllowed *    level)                                THREEWORDINLINE(0x303C, 0x021D, 0xA816);
  217.  
  218. EXTERN_API( OSErr )
  219. AESetInteractionAllowed            (AEInteractAllowed         level)                                THREEWORDINLINE(0x303C, 0x011E, 0xA816);
  220.  
  221. EXTERN_API( OSErr )
  222. AEInteractWithUser                (long                     timeOutInTicks,
  223.                                  NMRecPtr                 nmReqPtr,
  224.                                  AEIdleUPP                 idleProc)                            THREEWORDINLINE(0x303C, 0x061C, 0xA816);
  225.  
  226.  
  227. /**************************************************************************
  228.   These calls are used to set up and modify the event dispatch table.
  229. **************************************************************************/
  230. EXTERN_API( OSErr )
  231. AEInstallEventHandler            (AEEventClass             theAEEventClass,
  232.                                  AEEventID                 theAEEventID,
  233.                                  AEEventHandlerUPP         handler,
  234.                                  long                     handlerRefcon,
  235.                                  Boolean                 isSysHandler)                        THREEWORDINLINE(0x303C, 0x091F, 0xA816);
  236.  
  237. EXTERN_API( OSErr )
  238. AERemoveEventHandler            (AEEventClass             theAEEventClass,
  239.                                  AEEventID                 theAEEventID,
  240.                                  AEEventHandlerUPP         handler,
  241.                                  Boolean                 isSysHandler)                        THREEWORDINLINE(0x303C, 0x0720, 0xA816);
  242.  
  243. EXTERN_API( OSErr )
  244. AEGetEventHandler                (AEEventClass             theAEEventClass,
  245.                                  AEEventID                 theAEEventID,
  246.                                  AEEventHandlerUPP *    handler,
  247.                                  long *                    handlerRefcon,
  248.                                  Boolean                 isSysHandler)                        THREEWORDINLINE(0x303C, 0x0921, 0xA816);
  249.  
  250.  
  251. /**************************************************************************
  252.  The following four calls are available for applications which need more
  253.  sophisticated control over when and how events are processed. Applications
  254.  which implement multi-session servers or which implement their own
  255.  internal event queueing will probably be the major clients of these
  256.  routines. They can be called from within a handler to prevent the AEM from
  257.  disposing of the AppleEvent when the handler returns. They can be used to
  258.  asynchronously process the event (as MacApp does).
  259. **************************************************************************/
  260. EXTERN_API( OSErr )
  261. AESuspendTheCurrentEvent        (const AppleEvent *        theAppleEvent)                        THREEWORDINLINE(0x303C, 0x022B, 0xA816);
  262.  
  263. /* 
  264.  Note: The following routine tells the AppleEvent manager that processing
  265.  is either about to resume or has been completed on a previously suspended
  266.  event. The procPtr passed in as the dispatcher parameter will be called to
  267.  attempt to redispatch the event. Several constants for the dispatcher
  268.  parameter allow special behavior. They are:
  269.       - kAEUseStandardDispatch means redispatch as if the event was just
  270.       received, using the standard AppleEvent dispatch mechanism.
  271.       - kAENoDispatch means ignore the parameter.
  272.          Use this in the case where the event has been handled and no
  273.       redispatch is needed.
  274.       - non nil means call the routine which the dispatcher points to.
  275. */
  276. /* Constants for Refcon in AEResumeTheCurrentEvent with kAEUseStandardDispatch */
  277.  
  278. enum {
  279.     kAEDoNotIgnoreHandler        = 0x00000000,
  280.     kAEIgnoreAppPhacHandler        = 0x00000001,                    /* available only in vers 1.0.1 and greater */
  281.     kAEIgnoreAppEventHandler    = 0x00000002,                    /* available only in vers 1.0.1 and greater */
  282.     kAEIgnoreSysPhacHandler        = 0x00000004,                    /* available only in vers 1.0.1 and greater */
  283.     kAEIgnoreSysEventHandler    = 0x00000008,                    /* available only in vers 1.0.1 and greater */
  284.     kAEIngoreBuiltInEventHandler = 0x00000010,                    /* available only in vers 1.0.1 and greater */
  285.     kAEDontDisposeOnResume        = (long)0x80000000                /* available only in vers 1.0.1 and greater */
  286. };
  287.  
  288. /* Constants for AEResumeTheCurrentEvent */
  289.  
  290. enum {
  291.     kAENoDispatch                = 0,                            /* dispatch parameter to AEResumeTheCurrentEvent takes a pointer to a dispatch */
  292.     kAEUseStandardDispatch        = (long)0xFFFFFFFF                /* table, or one of these two constants */
  293. };
  294.  
  295. EXTERN_API( OSErr )
  296. AEResumeTheCurrentEvent            (const AppleEvent *        theAppleEvent,
  297.                                  const AppleEvent *        reply,
  298.                                  AEEventHandlerUPP         dispatcher,
  299.                                  long                     handlerRefcon)                        THREEWORDINLINE(0x303C, 0x0818, 0xA816);
  300.  
  301. EXTERN_API( OSErr )
  302. AEGetTheCurrentEvent            (AppleEvent *            theAppleEvent)                        THREEWORDINLINE(0x303C, 0x021A, 0xA816);
  303.  
  304. EXTERN_API( OSErr )
  305. AESetTheCurrentEvent            (const AppleEvent *        theAppleEvent)                        THREEWORDINLINE(0x303C, 0x022C, 0xA816);
  306.  
  307.  
  308. /**************************************************************************
  309.   These calls are used to set up and modify special hooks into the
  310.   AppleEvent manager.
  311. **************************************************************************/
  312. EXTERN_API( OSErr )
  313. AEInstallSpecialHandler            (AEKeyword                 functionClass,
  314.                                  UniversalProcPtr         handler,
  315.                                  Boolean                 isSysHandler)                        THREEWORDINLINE(0x303C, 0x0500, 0xA816);
  316.  
  317. EXTERN_API( OSErr )
  318. AERemoveSpecialHandler            (AEKeyword                 functionClass,
  319.                                  UniversalProcPtr         handler,
  320.                                  Boolean                 isSysHandler)                        THREEWORDINLINE(0x303C, 0x0501, 0xA816);
  321.  
  322. EXTERN_API( OSErr )
  323. AEGetSpecialHandler                (AEKeyword                 functionClass,
  324.                                  UniversalProcPtr *        handler,
  325.                                  Boolean                 isSysHandler)                        THREEWORDINLINE(0x303C, 0x052D, 0xA816);
  326.  
  327.  
  328. /**************************************************************************
  329.   This call was added in version 1.0.1. If called with the keyword
  330.   keyAERecorderCount ('recr'), the number of recorders that are
  331.   currently active is returned in 'result'
  332.   (available only in vers 1.0.1 and greater).
  333. **************************************************************************/
  334. EXTERN_API( OSErr )
  335. AEManagerInfo                    (AEKeyword                 keyWord,
  336.                                  long *                    result)                                THREEWORDINLINE(0x303C, 0x0441, 0xA816);
  337.  
  338.  
  339.  
  340.  
  341. #if PRAGMA_STRUCT_ALIGN
  342.     #pragma options align=reset
  343. #elif PRAGMA_STRUCT_PACKPUSH
  344.     #pragma pack(pop)
  345. #elif PRAGMA_STRUCT_PACK
  346.     #pragma pack()
  347. #endif
  348.  
  349. #ifdef PRAGMA_IMPORT_OFF
  350. #pragma import off
  351. #elif PRAGMA_IMPORT
  352. #pragma import reset
  353. #endif
  354.  
  355. #ifdef __cplusplus
  356. }
  357. #endif
  358.  
  359. #endif /* __APPLEEVENTS__ */
  360.  
  361.